FishMarket 1.0/FishMarket v1.0.iso/fishies/476-500/disk_494/vscreen/vscreen.doc

Text File | 1992-05-06 | 22KB | 423 lines

OVERVIEW:

VSCREEN allows you to have screens that are larger than the actual display
area of your monitor.  These larger "virtual" screens scroll when you move the
mouse off the edge of the visible section of the screen.  vScreen allows you
to create a screen large enough for a full page of editing, for example.  Not
all programs are set up to take advantage of vScreen, however, but most
programs that provide winodow-sizing gadgets can benefit from vScreen.

WARNING:  vScreen does devious and illegal things with the INTUITIONPRIVATE
section of the IntuitionBase structure.  Use it at your own risk.  vScreen is
likely to be incompatible with a future release of the system software.


HOW TO USE VSCREEN:

You should place vScreen in your C: directory (or in your current PATH).
vScreen-Handler should be in the L: directory (or the current directory).  To
start vScreen, issue the following command:

    1> VSCREEN width height ["screen-name"]

where  width  is the new width for the virtual screen,  height  is the new
height, and  "screen-name"  is the name of the screen that you want to make
larger.  If the screen name includes spaces or other special characters, you
should enclose it in quotation marks.  If you do not supply a screen name,
vScreen will enlarge the active screen.

The width and height should be at least as large as the current size of the
screen, and width and height should not be larger than 1024 (see the section
titled USAGE NOTES below).

For example, if you type

    1> VSCREEN 800 400

then the workbench screen will be enlarged to 800 by 400.

When you receive the "vScreen Installed" message, your screen will be a
virtual screen of the size you specified.

To view other parts of the virtual screen, simply move the mouse off the edge
of the visible portion of the screen so that it moves over the portion of the
screen that you want to see.  For example, if the upper left-hand corner of
the screen is showing, and you want to see the lower right-hand corner, just
move the mouse off the lower right-hand edge of the display.  The screen will
scroll to show you more of the screen in the direction that you moved the
mouse.

Note that the screen will scroll even when you are doing things that normally
"lock" the screen.  For example, if you are changing the size of a window or
dragging a window, and you move the mouse off the edge of the displayed
portion of the screen, the screen will still scroll.  The screen will not
scroll if you are dragging the screen, however, or if the virtual screen is
not the active screen.

You can force the screen to scroll without moving the mouse to the edge of the
screen by holding down the left-amiga key and moving the mouse.  This scrolls
the virtual screen while keeping the mouse at the same location on the display.

Note:  you can only have one virtual screen at a time under the current
release of vScreen (1.0.1).


If you want to remove vScreen and restore the normal sized screen, simply call
vScreen again:

    1> VSCREEN

You should receive a "vScreen removed" message.  vScreen will make sure that
all the windows currently open on the screen are moved and sized so that they
will fit on the normal sized screen.


USAGE NOTES:

When you enlarge a window using vScreen, the entire new screen is stored in
CHIP memory (not just the part that is currently showing).  For this reason,
vScreen may use up large pieces of CHIP memory.  Don't specify a screen that
is too large for the amount of memory that you have.  vScreen does not recover
well from low-memory conditions.

Although vScreen will allow you to specify a screen wider than 1024, you
should be aware that screens of this size can be a problem.  The blitter has a
limitation on the size of a block that it will move.  The RKM puts this limit
at 976 (see BltBitMap() in the autodocs), but empirical testing indicates that
values up to 1024 will work.  Above this size, blit operations fail to work
properly, so in a screen larger than 1024, dragged window may not update
correctly and the menu bar will not appear.

Similarly, screens taller than 1024 lines also can cause update problems.

vScreen will allow you to specify dimentions that are SMALLER than the current
screen, but this is not recommended.  vScreen will not function properly if a
screen is reduced in size.  Unexpected display effects will occur when the
screen is scrolled.

Due to the method used to display only a portion of the larger screen,
dragging a screen may incur noticably more overhead than usual.  This occurs
only when the virtual screen is the top-most screen and there is another
screen visable.  See the section on HOW VSCREEN WORKS for more details.

vScreen inserts an input handler in the Input.Device input chain and uses the
SetFunction() routine to replace Intuition and Graphics library routines.  For
this reason, only one copy of vScreen should be running at one time.  This
means that, under the current version of vScreen, you may only have one
virtual screen at a time.  If there is popular demand, a future release will
lift this restriction, and will provide a programmer's interface to vScreen.

If the virtual screen closes while vScreen is running, vScreen will become
disabled, but will not actaully be removed from the input chain or the library
vector tables (in order to keep the resident portion of vScreen as small as
possible, these functions are performed by the loader).  In order to actually
remove vScreen from the system, you must call vScreen a second time.  Note
that if you have set the workbench screen as a virtual screen and an
application calls CloseWorkBench() (and the screen actually closes), then when
the workbench is opened again, it no longer will be a virtual screen:  it will
have changed back to its original size.  You will have to remove the old copy
of vScreen (by calling vScreen with no parameters), and then re-install it to
make the workbench virtual again.

vScreen works with all view modes (lo-res, hi-res, interlace and HAM).  HAM
screens, however, may have discoloration along the left border when the left
edge is not showing.  This is due to the fact that the left edge of the
display will be the background color rather than the color of the previous
pixel that is not being displayed.

If the active screen is in front of the virtual screen and you move the mouse
so that it passes over the virtual screen, then the top window of the virtual
screen will become active (and the previous active screen will become
inactive).  See the section on HOW VSCREEN WORKS for more details on why
this is necessary under the current release of Intuition.

The Intuition window structure includes fields for the maximum size that the
window may have.  Most current programs that allow their windows to be
sized specify that the windows can be made arbitrarily large.  Some older
programs, however, specify maximum sizes equal to a standard sized screen
(e.g. 640 x 200).  These windows may not be able to grow as large as a virtual
screen.  For this reason, vScreen comes with a number of utilities that help
you to manipulate windows "by hand" (see OTHER UTILITIES below).


OTHER UTILITIES:

vScreen comes with four utility programs to help you manipulate windows on
virtual screens:  wSize wMove wMax and wList.

wSize allows you to change the size of any window, even if it does not have a
window sizing gadget.  To use wSize, issue the command:

    1> wSize dx dy ["window" ["screen" [IGNOREMAX]]]

where  dx  and  dy  are the number of pixels that the window should grow by in
the  x  and  y  directions (note that negative values are allowed).  "Window"
is the name of the window that is to be changed (if the name includes spaces
or other special characters it should be enclosed in quotation marks).  If no
name is specified then the active window is changed.  "Screen" is the name of
the screen where the window can be found (enclosed in quotation marks of the
name includes spaces).  If no screen name is specified then the active screen
is used.  The window will not shrink smaller than its minimum allowable size
(as stored in its window structure), and it will not grow larger than the
size of the screen, nor larger than its maximum size (as stored in its window
structure) unless IGNOREMAX is specified.

For example:

    1> wSize 50 25 "AmigaDOS"

will increase the size of the window named "AmgiaDOS" (on the current screen)
by 50 pixels in the  x  direction and 25 in the  y  direction.

You can use wSize to enlarge backdrop windows on screens that have them.
This is useful, for instance, for paint programs that render your picture
into a backdrop window without a sizing gadget.


wMove is similar to wSize, except that it moves the window rather than change
its size.  The parameters are the same (except there is no IGNOREMAX flag):

    1> wMove dx dy ["window" ["screen"]]

where  dx  and  dy  are the amounts by which to move the window, "window" is
the name of the window to move, and "screen" is the screen where that window
can be found.  The screen defaults to the current screen, and the window
defaults to the active window.  A window will not be moved off the edge of
the screen.


wMax allows you to change the maximum size setting that is stored in the
window's structure.  Call it with the following parameters:

    1> wMax x y ["window" ["screen"]]

where  x  is the maximum size horizontally, y  is the maximum size vertically,
"window" is the name of the window to change, and "screen" is the name of the
screen where that window can be found.  If the screen or window name contains
a space or special character, enclose the name in quotation marks.  If no
screen is specified, the active screen is used.  If no window is specified,
the active window is changed.  A size of -1 means that the window can be
stretched to any size in that direction.

For example:

    1> wMax -1 -1

allows the active window to grow to any size.


wList prints a list of all the windows on a specific screen, or all the
screens:

    1> wList ["screen"]

where "screen" is the name of the screen whose windows will be listed.  If
the screen name includes spaces or special characters, then enclose it in
quotation marks.  If no screen name is specified, then the names of all the
windows on all the screens are printed.

For example:

    1> wList "Workbench Screen"

will list the names of all the windows on the workbench.


HOW VSCREEN WORKS:

The graphics library defines a structure called a View, which represents the
entire visible area of the display.  The View is broken down into separate
ViewPorts.  Each ViewPort can have its own view mode (hi-res, interlace, HAM,
etc.), and each ViewPort can be a different size.

Intuition maintains a View (called the ViewLord), where each ViewPort
corresponds to an Intuition Screen (that's how screens can be of different
sizes and resolutions).  Windows within those screens have no direct analog
in the Graphics library (they correspond to Layers in the Layers library).

Each ViewPort has a related RasInfo structure that includes a pointer to its
bitmap.  When vScreen runs, it allocates new, larger bitplanes for the
ViewPort, and copies the data from the old planes into the new ones.  This
provides a larger bitmap for the corresponding screen.  Once this larger
bitmap is in place, all graphics calls proceed normally, as the Graphics
library handles the larger bitmap without trouble.

The RasInfo structure also includes two other fields:  RxOffset and RyOffset.
These represent the upper, left-hand corner of the section of bitmap that will
appear within the ViewPort.  Translated into Intuition terms, this tells what
part of a Screen's larger bitmap will be showing.  vScreen uses these offsets
to allow you to scroll the virtual screen; no memory is copied, so the
scrolling is very fast.

Unfortunately, Intuition does not take these offsets into account when it
figures the position of the mouse (when buttons are pressed, gadgets are
clicked, etc.).  The bulk of the vScreen-Handler is devoted to tricking
Intuition into handling these offset values correctly.

Initially, vScreen sets the screen width and height to the new size of the
screen.  When MakeScreen() is called for the virtual screen, and the screen is
the front screen, Intuition will set the ViewPort height to be the height of
the screen.  This would cause the screen to become an "overscan" screen when
it's not supposed to be.

Ideally, vScreen would trap the MakeScreen() call and change the value back.
Unfortunately, however, MakeScreen() is called by RethinkDisplay() and
RemakeDisplay(), which are both called by Intuition itself (when a new screen
is opened or moved, for example).  Since Intuition does not call its own jump
table vectors, we are not able to trap ALL the calls to MakeScreen(), so that
is not an effective method of fixing the problem.

Most often, after a MakeScreen() call, there will be calls to MrgCop() and
LoadView() (this is what happens with RethinkDisplay() and RemakeDisplay()).
Since LoadView() is in the Graphics library, not the Intuition library,
Intuition DOES call LoadView() through the graphics library vector table.
This provides a viable hook that we can use to fix the overscan problem.
Whenever LoadView() is called on the Intuition ViewLord, we check that the
ViewPort for the virtual screen does not have a height that is too large.  If
it does, we reduce the height and call MrgCop() again (this is what slows down
dragging the virtual screen when it is on top).

This fix to LoadView() makes the larger virtual screens display properly for
any given set of RxOffset and RyOffset.  The input handler is what changes
these offsets.  The handler adds up all the mouse movements within the input
event list, and adds them to the current Intuition MouseX and MouseY values.
If these would cause the mouse to move off the edge of the displayed area of
the screen, then the handler sets the offsets so that the mouse stays on the
screen.  The handler also checks for forced shifts (left amiga held down while
moving the mouse).

Once the screen is shifted, however, the mouse X and Y values can get very
large.  When Intuition positions the sprite that represents the mouse pointer,
it does not take RxOffset and RyOffset into account and hence can position
the pointer off the edge of the display.  For this reason, vScreen traps the
MoveSprite() graphics function, and when the virtual screen is active and
sprite zero is positioned, vScreen compensates for the offsets itself.  This
guarantees that the mouse pointer is positioned over the correct part of the
shifted virtual screen.

Intuition uses the MaxDisplayRows and MaxDisplayWidth to calculate the range
of X and Y values over which the mouse can travel (MinXMouse, MaxXMouse,
MinYMouse, and MaxYMouse).  The min and max values are changed when you drag a
window or screen, and when you change a window's size through its sizing
gadget.  In order to make it possible to move windows over the entire area of
the virtual screen, vScreen modifies the MaxDisplay values that Intuition uses.

At this point, the virtual screen works correctly; however, interactions
between the virtual screen and other screens do not.  Intuition does not take
into account the RasInfo offsets when it calculates the position of the top of
the screen.  For example, if the virtual screen is shifted vertially so that
the top 20 lines are not showing, and another screen is visible behind the
virtual screen, and you click in that screen but within 20 lines of the top of
the virtual screen, Intuition will think you clicked in the virtual screen
itself (in the upper area that is not currently showing).  Worse yet, if you
click higher up in the other screen (over 20 lines above the top of the
virtual screen), Intuition will see that you hit the other screen, but will
think the mouse is 20 lines lower than it is.  This is because the Intuition
MouseY value is off by RyOffset pixels.

To avoid these problems, vScreen monitors the mouse movements to tell when the
mouse changes from being over the virtual screen to being over some other
screen.  When the pointer moves over some other screen, vScreen resets the
MouseX and MouseY values to their normal positions.  That way, if a mouse
click occurs in the other screen, it will occur at the proper place.  When the
pointer moves back over the virtual screen, the MouseX and MouseY are returned
to their positions relative to the virtual screen's RxOffset and RyOffset
values.

This works fine whenever the virtual screen is the active screen and the
pointer moves over another screen either in front of or behind the virtual
screen.  It also works if a screen behind the virtual screen is active and
the mouse moves over the virtual screen.  It does not work, however, if a
screen in front of the virtual screen is active and the mouse moves over the
virtual screen.  In this case, if the MouseY value were changed and the mouse
button pressed, Intuition would incorrectly think the mouse was positioned
over the active screen.  For this reason, when a non-virtual screen is active
and in front of the virtual screen, and the mouse moves over the virtual
screen, the virtual screen is activated.  This is not consistant with normal
Intuition actions, but does ensure that mouse clicks will be reported correctly.

Normally, you can move the mouse pointer past the top edge of a screen so that
it is over another screen and the virtual screen will not scroll until the
pointer hits the top of the physical display.  If you are dragging a window,
however, or are holding down the menu button, or doing some other action that
locks the screen layers, then the screen will scroll when you move the pointer
past the top of the screen (rather than waiting until it reaches the top of
the display).  This makes it easier to select menus when the screen is
scrolled vertically, for instance.

If an AutoRequest() occurs on the virtual screen, the screen will automatically
shift so that the upper left-hand corner is showing (just like the screen
where an AutoRequest occurs will be brought to the front).

If BuildSysRequest() is called on the virtual screen, then rather than shift
the screen, vScreen moves the request window so that it appears in the upper
left-hand corner of the displayed area of the screen.  Ideally, this is what
we should do for AutoRequest(), but since Intuition does not call its own
vector table, we can not trap the BuildSysRequest() call made by AutoRequest().

Finally, vScreen traps calls to CloseScreen() so that it can tell when the
virtual screen is closed.  If the virtual screen closes, vScreen will cease
all its functions, but will not actually restore the trapped vectors or remove
the input handler or free its memory until you remove vScreen by calling
vScreen a second time.

I do not recommend that you use this approach in your own programs.
Modifying, or even viewing, the INTUITIONPRIVATE data structure is frowned
upon by Commodore-Amiga, and will make your programs unreliable in future
versions of Intuition.  Furthermore, if more than one program uses this
method, they will probably interact destructively.  If there is sufficient
demand, and provided Commodore does not incorporate something like this in a
future release of Intuition, I may be convinced to put this functionality
into a library with a callable interface for programs to use.


COMPILING VSCREEN:

vScreen was developed using the Lattice C compiler v4.0 on a 512K Amiga 1000.
It probably will need to be changed in order to work with Manx Aztec C.  To
compile and link vScreen use the following commands:

    1> lc -v -b0 vScreen vScreenSetup vScreen-Handler
    1> asm vScreenStubs
    1> blink with vScreen.lnk
    1> blink with vScreen-Handler.lnk

I prefer not to use the Lattice function prototypes, but I like to use the
direct-library-call preprocessor commands, therefore, I have modified my
prototype include files to remove the function prototypes (via an #ifdef).
If you compile the source files with the -dPROTO flag, then the Lattice proto
include files will be used (there will be compile-time warnings), otherwise,
they will not be included.


AUTHOR:

vScreen and vScreen-Handler
Copyright 1988 by Davide P. Cervone, All rights reserved.

You may distribute this program and source code for non-commercial purposes,
provided you include this documentation.  You may not ditribute this program
as part of a commercial product without the author's written permission.
You may not include this source code as part of your own programs.

(Sorry about the restrictions on the use of vScreen, but I think that using
the INTUITIONPRIVATE stuff is a terrible thing to do, and I don't want it to
appear in any commercial products.  I'm hoping that Commodore-Amiga will pick
up on the idea and incorporate it into Intuition, where it belongs, and where
it would be much easier to do.  If they don't, then I plan to do my own
virtual screen library, and I don't want anyone else's programs to break, or
to get in the way).

If you find an interesting use for vScreen, please drop me a note.


AUTHOR:

vScreen and vScreen-Handler
Copyright (c) 1988 by Davide P. Cervone, all rights reserved.

Davide P. Cervone
Department of Mathematics, Box 1917                 [e-mail]
Brown University                                    [e-mail]
Providence, Rhode Island  02912                     [e-mail]